home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / knotifyclient.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  10.6 KB  |  326 lines
  1. /* This file is part of the KDE libraries
  2.    Copyright (C) 2000 Charles Samuels <charles@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License version 2 as published by the Free Software Foundation.
  7.  
  8.    This library is distributed in the hope that it will be useful,
  9.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11.    Library General Public License for more details.
  12.  
  13.    You should have received a copy of the GNU Library General Public License
  14.    along with this library; see the file COPYING.LIB.  If not, write to
  15.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16.    Boston, MA 02110-1301, USA.
  17. */
  18. #ifndef _KNOTIFY_CLIENT
  19. #define _KNOTIFY_CLIENT
  20. #include <qstring.h>
  21. #include "kdelibs_export.h"
  22.  
  23. class KInstance;
  24. #undef None // X11 headers...
  25.  
  26. /**
  27.  * This namespace provides a method for issuing events to a KNotifyServer
  28.  * call KNotifyClient::event("eventname"); to issue it.
  29.  * On installation, there should be a file called
  30.  * $KDEDIR/share/apps/appname/eventsrc which contains the events.
  31.  *
  32.  * The file looks like this:
  33.  * \code
  34.  * [!Global!]
  35.  * IconName=Filename (e.g. kdesktop, without any extension)
  36.  * Comment=FriendlyNameOfApp
  37.  *
  38.  * [eventname]
  39.  * Name=FriendlyNameOfEvent
  40.  * Comment=Description Of Event
  41.  * default_sound=filetoplay.wav
  42.  * default_logfile=logfile.txt
  43.  * default_commandline=command
  44.  * default_presentation=1
  45.  *  ...
  46.  * \endcode
  47.  * default_presentation contains these ORed events:
  48.  *    None=0, Sound=1, Messagebox=2, Logfile=4, Stderr=8, PassivePopup=16,
  49.  *      Execute=32, Taskbar=64
  50.  *
  51.  * KNotify will search for sound files given with a relative path first in
  52.  * the application's sound directory (share/apps/Application Name/sounds), then in
  53.  * the KDE global sound directory (share/sounds).
  54.  *
  55.  * You can also use the "nopresentation" key, with any the presentations
  56.  * ORed.  Those that are in that field will not appear in the kcontrol
  57.  * module.  This was intended for software like KWin to not allow a window-opening
  58.  * that opens a window (e.g., allowing to disable KMessageBoxes from appearing)
  59.  * If the user edits the eventsrc file manually, it will appear.  This only
  60.  * affects the KcmNotify.
  61.  *
  62.  * You can also use the following events, which are system controlled
  63.  * and do not need to be placed in your eventsrc:
  64.  *
  65.  *<ul>
  66.  * <li>cannotopenfile
  67.  * <li>notification
  68.  * <li>warning
  69.  * <li>fatalerror
  70.  * <li>catastrophe
  71.  *</ul>
  72.  *
  73.  * The events can be configured in an application using KNotifyDialog, which is part of KIO.
  74.  * 
  75.  * @author Charles Samuels <charles@kde.org>
  76.  */
  77.  
  78.  
  79. namespace KNotifyClient
  80. {
  81.     struct InstancePrivate;
  82.     class InstanceStack;
  83.  
  84.     /**
  85.      * Makes it possible to use KNotifyClient with a KInstance
  86.      * that is not the application.
  87.      *
  88.      * Use like this:
  89.      * \code
  90.      * KNotifyClient::Instance(myInstance);
  91.      * KNotifyClient::event("MyEvent");
  92.      * \endcode
  93.      *
  94.      * @short Enables KNotifyClient to use a different KInstance
  95.      */
  96.     class KDECORE_EXPORT Instance
  97.     {
  98.     public:
  99.         /**
  100.          * Constructs a KNotifyClient::Instance to make KNotifyClient use
  101.          * the specified KInstance for the event configuration.
  102.      * @param instance the instance for the event configuration
  103.          */
  104.         Instance(KInstance *instance);
  105.         /**
  106.          * Destructs the KNotifyClient::Instance and resets KNotifyClient
  107.          * to the previously used KInstance.
  108.          */
  109.         ~Instance();
  110.     /**
  111.      * Checks whether the system bell should be used.
  112.      * @returns true if this instance should use the System bell instead
  113.      * of KNotify.
  114.      */
  115.     bool useSystemBell() const;
  116.         /**
  117.          * Returns the currently active KInstance.
  118.      * @return the active KInstance
  119.          */
  120.         static KInstance *current();
  121.  
  122.     /**
  123.      * Returns the current KNotifyClient::Instance (not the KInstance).
  124.      * @return the active Instance
  125.      */
  126.     static Instance *currentInstance();
  127.     
  128.     private:
  129.         static InstanceStack *instances();
  130.         InstancePrivate *d;
  131.         static InstanceStack *s_instances;
  132.     };
  133.  
  134.  
  135.     /**
  136.      * Describes the notification method.
  137.      */
  138.     enum {
  139.         Default = -1,
  140.         None = 0,
  141.         Sound = 1,
  142.         Messagebox = 2,
  143.         Logfile = 4,
  144.         Stderr = 8,
  145.         PassivePopup = 16, ///< @since 3.1
  146.         Execute = 32,      ///< @since 3.1
  147.         Taskbar = 64       ///< @since 3.2
  148.     };
  149.  
  150.     /**
  151.      * Describes the level of the error.
  152.      */
  153.     enum {
  154.         Notification=1,
  155.         Warning=2,
  156.         Error=4,
  157.         Catastrophe=8
  158.     };
  159.  
  160.     /**
  161.      * default events you can use
  162.      */
  163.     enum StandardEvent {
  164.         cannotOpenFile,
  165.         notification,
  166.         warning,
  167.         fatalError,
  168.         catastrophe
  169.     };
  170.  
  171.     /**
  172.      * This starts the KNotify Daemon, if it's not already started.
  173.      * This will be useful for games that use sound effects. Run this
  174.      * at the start of the program, and there won't be a pause when it is
  175.      * first triggered.
  176.      * @return true if daemon is running (always true at the moment)
  177.      **/
  178.     KDECORE_EXPORT bool startDaemon();
  179.  
  180. //#ifndef KDE_NO_COMPAT
  181.     /**
  182.      * @deprecated
  183.      * @param message The name of the event
  184.      * @param text The text to put in a dialog box.  This won't be shown if
  185.      *             the user connected the event to sound, only. Can be QString::null.
  186.      * @return a value > 0, unique for this event if successful, 0 otherwise
  187.      */
  188.     KDECORE_EXPORT int event(const QString &message, const QString &text=QString::null) KDE_DEPRECATED;
  189.  
  190.     /**
  191.      * @deprecated
  192.      * Allows to easily emit standard events.
  193.      * @param event The event you want to raise.
  194.      * @param text The text explaining the event you raise. Can be QString::null.
  195.      * @return a value > 0, unique for this event if successful, 0 otherwise
  196.      */
  197.     KDECORE_EXPORT int event( StandardEvent event, const QString& text=QString::null ) KDE_DEPRECATED;
  198.  
  199.     /**
  200.      * @deprecated
  201.      * Will fire an event that's not registered.
  202.      * @param text The error message text, if applicable
  203.      * @param present The presentation method(s) of the event
  204.      * @param level The error message level, defaulting to "Default"
  205.      * @param sound The sound file to play if selected with @p present
  206.      * @param file The log file to append the message to if selected with @p present
  207.      * @return a value > 0, unique for this event if successful, 0 otherwise
  208.      */
  209.     KDECORE_EXPORT int userEvent(const QString &text=QString::null, int present=Default, int level=Default,
  210.                                  const QString &sound=QString::null, const QString &file=QString::null) KDE_DEPRECATED;
  211.     
  212. //#endif
  213.  
  214.     /**
  215.      * This should be the most used method in here.
  216.      * Pass the origin-widget's winId() here so that a PassivePopup can be
  217.      * placed appropriately.
  218.      *
  219.      * Call it by KNotifyClient::event(widget->winId(), "EventName");
  220.      * It will use KApplication::kApplication->dcopClient() to communicate to
  221.      * the server
  222.      * @param winId The winId() of the widget where the event originates
  223.      * @param message The name of the event
  224.      * @param text The text to put in a dialog box.  This won't be shown if
  225.      *             the user connected the event to sound, only. Can be QString::null.
  226.      * @return a value > 0, unique for this event if successful, 0 otherwise
  227.      * @since 3.1.1
  228.      */
  229.     // KDE4: use WId instead of int
  230.     KDECORE_EXPORT int event( int winId, const QString& message,
  231.                               const QString& text = QString::null );
  232.  
  233.     /**
  234.      * You should
  235.      * pass the origin-widget's winId() here so that a PassivePopup can be
  236.      * placed appropriately.
  237.      * @param winId The winId() of the widget where the event originates
  238.      * @param event The event you want to raise
  239.      * @param text The text to put in a dialog box.  This won't be shown if
  240.      *             the user connected the event to sound, only. Can be QString::null.
  241.      * @return a value > 0, unique for this event if successful, 0 otherwise
  242.      * @since 3.1.1
  243.      */
  244.     // KDE4: use WId instead of int
  245.     KDECORE_EXPORT int event( int winId, StandardEvent event,
  246.                               const QString& text = QString::null );
  247.  
  248.     /**
  249.      * Will fire an event that's not registered.
  250.      * You should
  251.      * pass the origin-widget's winId() here so that a PassivePopup can be
  252.      * placed appropriately.
  253.      * @param winId The winId() of the originating widget
  254.      * @param text The error message text, if applicable
  255.      * @param present The presentation method(s) of the event
  256.      * @param level The error message level, defaulting to "Default"
  257.      * @param sound The sound file to play if selected with @p present
  258.      * @param file The log file to append the message to if selected with @p present
  259.      * @return a value > 0, unique for this event if successful, 0 otherwise
  260.      * @since 3.1.1
  261.      */
  262.     // KDE4: use WId instead of int
  263.     KDECORE_EXPORT int userEvent(int winId, const QString &text=QString::null, int present=Default, int level=Default,
  264.                           const QString &sound=QString::null, const QString &file=QString::null);
  265.     
  266.     /**
  267.      * This is a simple substitution for QApplication::beep().
  268.      * It simply calls
  269.      * \code
  270.      * KNotifyClient::event( KNotifyClient::notification, reason );
  271.      * \endcode
  272.      * @param reason the reason, can be QString::null.
  273.      */
  274.     KDECORE_EXPORT void beep(const QString& reason=QString::null);
  275.  
  276.     /**
  277.      * Gets the presentation associated with a certain event name
  278.      * Remeber that they may be ORed:
  279.      * \code
  280.      * if (present & KNotifyClient::Sound) { [Yes, sound is a default] }    
  281.      * \endcode
  282.      * @param eventname the event name to check
  283.      * @return the presentation methods
  284.      */
  285.     KDECORE_EXPORT int getPresentation(const QString &eventname);
  286.     
  287.     /**
  288.      * Gets the default file associated with a certain event name
  289.      * The control panel module will list all the event names
  290.      * This has the potential for being slow.
  291.      * @param eventname the name of the event
  292.      * @param present the presentation method
  293.      * @return the associated file. Can be QString::null if not found.
  294.      */
  295.     KDECORE_EXPORT QString getFile(const QString &eventname, int present);
  296.     
  297.     /**
  298.      * Gets the default presentation for the event of this program.
  299.      * Remember that the Presentation may be ORed.  Try this:
  300.      * \code
  301.      * if (present & KNotifyClient::Sound) { [Yes, sound is a default] }
  302.      * \endcode
  303.      * @return the presentation methods
  304.      */
  305.     KDECORE_EXPORT int getDefaultPresentation(const QString &eventname);
  306.     
  307.     /**
  308.      * Gets the default File for the event of this program.
  309.      * It gets it in relation to present.
  310.      * Some events don't apply to this function ("Message Box")
  311.      * Some do (Sound)
  312.      * @param eventname the name of the event
  313.      * @param present the presentation method
  314.      * @return the default file. Can be QString::null if not found.
  315.      */
  316.     KDECORE_EXPORT QString getDefaultFile(const QString &eventname, int present);
  317.  
  318.     /**
  319.      * Shortcut to KNotifyClient::Instance::current() :)
  320.      * @returns the current KInstance.
  321.      */
  322.     KDECORE_EXPORT KInstance * instance();
  323. }
  324.  
  325. #endif
  326.